Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 2 - Control Manager Reference / Control Manager Functions

Defining Your Own User Pane Functions /

MyUserPaneTrackingProc

NEW WITH THE APPEARANCE MANAGER

Tracks a control while the user holds down the mouse button.

The Control Manager declares the type for an application-defined user pane tracking function as follows:

typedef pascal ControlPartCode (*ControlUserPaneTrackingProc)(
                                 ControlHandle control,
                                 Point startPt,
                                 ControlActionUPP actionProc);

The Control Manager defines the data type ControlUserPaneTrackingUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlUserPaneTrackingUPP;

You typically use the NewControlUserPaneTrackingingProc macro like this:

ControlUserPaneTrackingUPP myControlUserPaneTrackingUPP;
myControlUserPaneTrackingUPP = NewControlUserPaneTrackingProc
(MyUserPaneTracking);

You typically use the CallControlUserPaneTrackingingProc macro like this:

CallControlUserPaneTrackingProc(myControlUserPaneTrackingUPP, control, startPt, actionProc);

Here's how to declare the function MyUserPaneTrackingProc:

pascal ControlPartCode MyUserPaneTrackingProc (
                     ControlHandle control,
                     Point startPt,
                     ControlActionUPP actionProc);

control

A handle to the control in which the mouse-down event occurred.

startPt

The location of the cursor at the time the mouse button was first pressed, in local coordinates. Your application retrieves this point from the where field of the event structure.

actionProc

A pointer to an action function defining what action your application takes while the user holds down the mouse button. The value of the actionProc parameter can be a valid procPtr, nil, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like nil).

function result

Returns the part code of the control part that was tracked. If tracking was unsuccessful, kControlNoPartCode is returned.

DISCUSSION

Your MyUserPaneTrackingProc function should track the control by repeatedly calling the action function specified in the actionProc parameter until the mouse button is released. When the mouse button is released, your function should return the part code of the control part that was tracked.

This function will only get called if you've set the kControlHandlesTracking feature bit on creation of the user pane control. Once you have created the function MyUserPaneTrackingProc, pass kControlUserPaneTrackingProcTag in the tagName parameter of SetControlData.